Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Mig.man < prev next >

Wrap

Text File | 1990-04-06 | 14.2 KB | 399 lines

Mig C Library Procedures Mig _________________________________________________________________ NNAAMMEE Mig - obtain or update information in the migration informa- tion database. SSYYNNOOPPSSIISS ##iinncclluuddee <<mmiigg..hh>> Mig_Info * MMiigg__GGeettIInnffoo(_s_p_r_i_t_e_I_D) int MMiigg__GGeettAAllllIInnffoo(_i_n_f_o_A_r_r_a_y, _n_u_m_H_o_s_t_s) int MMiigg__RReeqquueessttIIddlleeHHoossttss(_n_u_m_H_o_s_t_s, _p_r_i_o_r_i_t_y, _f_l_a_g_s, _c_a_l_l_B_a_c_k_P_t_r, _h_o_s_t_A_r_r_a_y) int MMiigg__CCoonnffiirrmmIIddllee(_s_p_r_i_t_e_I_D) int MMiigg__RReettuurrnnHHoossttss(_n_u_m_H_o_s_t_s, _h_o_s_t_A_r_r_a_y) int MMiigg__DDeelleetteeHHoosstt(_s_p_r_i_t_e_I_D) int MMiigg__EEvviicctt() char * MMiigg__GGeettPPddeevvNNaammee(_g_l_o_b_a_l) int MMiigg__GGeettIIddlleeNNooddee() int MMiigg__DDoonnee(_s_p_r_i_t_e_I_D) AARRGGUUMMEENNTTSS int _s_p_r_i_t_e_I_D (in) The Sprite ID of the host for which informa- tion should be obtained or updated. Mig_Info _i_n_f_o_A_r_r_a_y[](out) A buffer to hold Mig_Info entries returned by the Mig_GetAllInfo routine. The size of the buffer Sprite v.1.0 Printed: April 5, 1990 1 Mig C Library Procedures Mig is specified in the _n_u_m_H_o_s_t_s variable. int _n_u_m_H_o_s_t_s (in) The number of Mig_Info structures contained in _i_n_f_o_A_r_r_a_y. Or, the number of hosts requested from MMiigg__RReeqquueessttIIddlleeHHoossttss and the number of hosts returned to MMiigg__RReettuurrnnIIddllee. int _p_r_i_o_r_i_t_y (in) Priority of processes to be migrated to idle hosts (see below). int _f_l_a_g_s (in) Flags to be passed to the migration daemon (see below). void (*_c_a_l_l_B_a_c_k_P_t_r)() (in) Routine to call if not enough hosts are avail- able and additional hosts are later avail- able. int _g_l_o_b_a_l (in) Whether to return the name of the pseudo- device for the global daemon or host-specific daemon. _________________________________________________________________ DDEESSCCRRIIPPTTIIOONN These functions are used to obtain (or update) information about hosts on the Sprite network. There are routines to get information about specific hosts or all the hosts on the network, to select one or more idle hosts for process migra- tion, to cause processes to be evicted, or to remove hosts that are down from the list of hosts on the network. Most of the routines interact with a single network-wide daemon, known as the _g_l_o_b_a_l _d_a_e_m_o_n, to obtain information or make requests. This mmiiggdd daemon maintains state about all hosts on the network, including their load averages, idle time, and availability for use with migration. In addi- tion, each host runs a per-host instance of mmiiggdd that sam- ples load and evicts processes automatically when it detects user input. The MMiigg library opens a pseudo-device to com- municate with the appropriate mmiiggdd daemon (global or local) depending on the operation being performed. Also, if an error occurs communicating with a daemon, the MMiigg library Sprite v.1.0 Printed: April 5, 1990 2 Mig C Library Procedures Mig reestablishes communication. GGEETTTTIINNGG HHOOSSTT IINNFFOORRMMAATTIIOONN The migration daemon, and the migration library, communicate using a structure defined in mig.h, known as a Mig_Info structure. Each host has a Mig_Info structure associated with it. The structure has another structure included within it; the Mig_LoadVector is updated periodically by the mmiiggdd process on each host. The rest of the data in a Mig_Info structure are established at boot-time or are main- tained by the global daemon. The global daemon maintains the state of each host. The states are defined in mig.h. The most important ones are MIG_HOST_DOWN, which indicates that the rest of the Mig_Info structure is irrelevant with the exception of loadVec.timestamp, which indicates when the host was last up; MIG_HOST_IDLE, indicating that a host is available for migration; MIG_HOST_FULL, which shows that the host is accepting migration but already has foreign processes; and MIG_HOST_ACTIVE, which indicates that a user is actively using the machine or the machine's load is too high to per- mit foreign processes. The load vector includes weighted average CPU utilizations and ready-queue lengths, as well as the time since input was last received from users directly logged into the machine. (Remote logins do not affect idle time.) Finally, each entry indicates whether the host is willing to accept processes for migration. mmiiggdd is responsible for determin- ing whether migration is allowed, based on factors such as load and idle time. MMiigg__GGeettIInnffoo(()) returns a pointer to a Mig_Info structure based on the sprite ID of a host. The structure is stati- cally allocated by Mig_GetInfo, and the contents of the structure may change on subsequent calls to Mig_GetInfo. On error, a NULL pointer is returned. MMiigg__GGeettAAllllIInnffoo(()) returns an array of Mig_Info structures. The array must be allocated by the caller, and a pointer to the array must be passed to MMiigg__GGeettAAllllIInnffoo(()), along with the size of the array. The number of entries filled in infoAr- ray iiss rreettuurrnneedd.. OOnn eerrrroorr,, --11 iiss rreettuurrnneedd aanndd tthhee gglloobbaall vvaarriiaabbllee _e_r_r_n_o iinnddiiccaatteess tthhee nnaattuurree ooff tthhee eerrrroorr.. GGEETTTTIINNGG IIDDLLEE HHOOSSTTSS The global daemon maintains open connections to both per- host mmiiggdd daemons and user processes that are using idle hosts. User processes can request idle hosts using any of three priorities, MIG_LOW_PRIORITY, MIG_NORMAL_PRIORITY, and MIG_HIGH_PRIORITY. MIG_LOW_PRIORITY is for long-running Sprite v.1.0 Printed: April 5, 1990 3 Mig C Library Procedures Mig background processes that are to be run at low execution priority. MIG_NORMAL_PRIORITY is for normal, relatively short-lived processes such as compiles. MIG_HIGH_PRIORITY is not yet in general use. Hosts with foreign processes of one priority can still accept more processes of higher priority, so simulations won't interfere with compiles. Processes communicate with the global daemon using ioctls, and normally, those streams are not readable. The global daemon makes the streams readable to indicate that a change of state has occurred. The MMiigg library relies on sseelleecctt(()) to determine whether the global daemon has information about changes. In this way, communication with the daemon may be minimized, since applications can check for new idle hosts or evictions on hosts they were using, without ever communi- cating with the daemon. MMiigg__RReeqquueessttIIddlleeHHoossttss(()) requests one or more idle hosts from the global daemon. The number of hosts available is returned. The _p_r_i_o_r_i_t_y must be specified as one of the priorities listed above. The _f_l_a_g_s may be 0 or MIG_PROC_AGENT, which indicates that the process requesting the host will not indicate when the processes being migrated are through, and instead the hosts to which the processes are migrated should monitor foreign processes and note when they are no longer in use for migration. The _c_a_l_l_B_a_c_k_P_t_r may be NULL or a pointer to a void function that will be invoked when additional hosts are available, if an insuffi- cient number of hosts are granted by the global daemon at the time of the call. _h_o_s_t_A_r_r_a_y points to an area that can hold up to _n_u_m_H_o_s_t_s host identifiers. MMiigg__CCoonnffiirrmmIIddllee((_h_o_s_t_I_D)) verifies that a host is still avail- able. If the host is available, MMiigg__CCoonnffiirrmmIIddllee(()) returns 1 (TRUE). If the host is not available, or an error occurs, MMiigg__CCoonnffiirrmmIIddllee(()) returns 0 (FALSE). In this case, the caller may request a new idle host. MMiigg__RReettuurrnnHHoossttss(()) returns one or more idle hosts to the pool. Note: all hosts requested by a process are returned to the pool of idle hosts when the stream that connects the process to the global daemon is closed (i.e., when the pro- cess and all its children that may have inherited the stream have exited). BBAACCKKWWAARRDD CCOOMMPPAATTIIBBIILLIITTYY Two functions are implemented to provide a backward compati- ble interface for users of the original MMiigg library. MMiigg__GGeettIIddlleeNNooddee(()) returns the number of an idle node. If no host is available, then 0 is returned. On error, -1 is returned and the global variable _e_r_r_n_o indicates the nature Sprite v.1.0 Printed: April 5, 1990 4 Mig C Library Procedures Mig of the error. MMiigg__DDoonnee(()) returns a single host to the pool of idle hosts. MMIISSCCEELLLLAANNEEOOUUSS MMiigg__DDeelleetteeHHoosstt(()) removes a host from the database maintained by the global daemon. The host must be down at the time. This may be used if a host is removed from the network or renamed. MMiigg__EEvviicctt(()) performs an _i_o_c_t_l to the local mmiiggdd daemon, requesting that it evict any foreign processes. Normally, eviction is automatic when a host becomes active after being idle. This routine provides the llooaaddaavvgg program with the ability to request evictions at other times (for example, from a remote login). MMiigg__GGeettPPddeevvNNaammee(()) is used by the migration library and by mmiiggdd to get the name of pseudo-devices to open. It would not normally be used by other programs. DDIIAAGGNNOOSSTTIICCSS Most MMiigg routines return zero if all went well. Otherwise they return -1 and the _e_r_r_n_o variable contains additional information about what error occurred. MMiigg__GGeettIIddlleeNNooddee(()) and MMiigg__RReeqquueessttIIddlleeHHoossttss(()) similarly return -1 on error, but they return 0 if no idle host is available. MMiigg__GGeettIInnffoo(()) returns NULL on error. FFIILLEESS /sprite/admin/migd.log The global migration daemon error log. /hosts/$HOST/migd.log The error log used by host $HOST. /sprite/admin/migInfo.pdev The pseudo-device used to communicate with the global daemon. /hosts/$HOST/migInfo.pdev The pseudo-device used to communicate with the local daemon. /sprite/admin/migd.check The file used to store the most recent information about host uptimes. KKEEYYWWOORRDDSS migration, load average, idle time, pseudo-device, eviction Sprite v.1.0 Printed: April 5, 1990 5 Mig C Library Procedures Mig SSEEEE AALLSSOO migd, loadavg, pmake, pdev Sprite v.1.0 Printed: April 5, 1990 6